home *** CD-ROM | disk | FTP | other *** search
/ isnet Internet / Isnet Internet CD.iso / prog / hiz / 09 / 09.exe / adynware.exe / perl / lib / Text / Soundex.pm < prev    next >
Encoding:
Perl POD Document  |  1999-12-28  |  3.2 KB  |  117 lines
  1. package Text::Soundex;
  2. require 5.000;
  3. require Exporter;
  4.  
  5. @ISA = qw(Exporter);
  6. @EXPORT = qw(&soundex $soundex_nocode);
  7.  
  8.  
  9.  
  10. $soundex_nocode = undef;
  11.  
  12. sub soundex
  13. {
  14.   local (@s, $f, $fc, $_) = @_;
  15.  
  16.   push @s, '' unless @s;    # handle no args as a single empty string
  17.  
  18.   foreach (@s)
  19.   {
  20.     $_ = uc $_;
  21.     tr/A-Z//cd;
  22.  
  23.     if ($_ eq '')
  24.     {
  25.       $_ = $soundex_nocode;
  26.     }
  27.     else
  28.     {
  29.       ($f) = /^(.)/;
  30.       tr/AEHIOUWYBFPVCGJKQSXZDTLMNR/00000000111122222222334556/;
  31.       ($fc) = /^(.)/;
  32.       s/^$fc+//;
  33.       tr///cs;
  34.       tr/0//d;
  35.       $_ = $f . $_ . '000';
  36.       s/^(.{4}).*/$1/;
  37.     }
  38.   }
  39.  
  40.   wantarray ? @s : shift @s;
  41. }
  42.  
  43. 1;
  44.  
  45. __END__
  46.  
  47. =head1 NAME
  48.  
  49. Text::Soundex - Implementation of the Soundex Algorithm as Described by Knuth
  50.  
  51. =head1 SYNOPSIS
  52.  
  53.   use Text::Soundex;
  54.  
  55.   $code = soundex $string;            # get soundex code for a string
  56.   @codes = soundex @list;             # get list of codes for list of strings
  57.  
  58.  
  59.   $soundex_nocode = 'Z000';
  60.  
  61. =head1 DESCRIPTION
  62.  
  63. This module implements the soundex algorithm as described by Donald Knuth
  64. in Volume 3 of B<The Art of Computer Programming>.  The algorithm is
  65. intended to hash words (in particular surnames) into a small space using a
  66. simple model which approximates the sound of the word when spoken by an English
  67. speaker.  Each word is reduced to a four character string, the first
  68. character being an upper case letter and the remaining three being digits.
  69.  
  70. If there is no soundex code representation for a string then the value of
  71. C<$soundex_nocode> is returned.  This is initially set to C<undef>, but
  72. many people seem to prefer an I<unlikely> value like C<Z000>
  73. (how unlikely this is depends on the data set being dealt with.)  Any value
  74. can be assigned to C<$soundex_nocode>.
  75.  
  76. In scalar context C<soundex> returns the soundex code of its first
  77. argument, and in array context a list is returned in which each element is the 
  78. soundex code for the corresponding argument passed to C<soundex> e.g.
  79.  
  80.   @codes = soundex qw(Mike Stok);
  81.  
  82. leaves C<@codes> containing C<('M200', 'S320')>.
  83.  
  84. =head1 EXAMPLES
  85.  
  86. Knuth's examples of various names and the soundex codes they map to
  87. are listed below:
  88.  
  89.   Euler, Ellery -> E460
  90.   Gauss, Ghosh -> G200
  91.   Hilbert, Heilbronn -> H416
  92.   Knuth, Kant -> K530
  93.   Lloyd, Ladd -> L300
  94.   Lukasiewicz, Lissajous -> L222
  95.  
  96. so:
  97.  
  98.   $code = soundex 'Knuth';              # $code contains 'K530'
  99.   @list = soundex qw(Lloyd Gauss);    # @list contains 'L300', 'G200'
  100.  
  101. =head1 LIMITATIONS
  102.  
  103. As the soundex algorithm was originally used a B<long> time ago in the US
  104. it considers only the English alphabet and pronunciation.
  105.  
  106. As it is mapping a large space (arbitrary length strings) onto a small
  107. space (single letter plus 3 digits) no inference can be made about the
  108. similarity of two strings which end up with the same soundex code.  For 
  109. example, both C<Hilbert> and C<Heilbronn> end up with a soundex code
  110. of C<H416>.
  111.  
  112. =head1 AUTHOR
  113.  
  114. This code was implemented by Mike Stok (C<stok@cybercom.net>) from the 
  115. description given by Knuth.  Ian Phillips (C<ian@pipex.net>) and Rich Pinder 
  116. (C<rpinder@hsc.usc.edu>) supplied ideas and spotted mistakes.
  117.